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Status of this Memo 


This RFC describes a protocol that International Business Machines 
Corporation (IBM) has been implementing in most of its SNMP agents to 
allow dynamic extension of supported MIBs. This is an Experimental 
Protocol for the Internet community. Discussion and suggestions for 
improvement are requested. Please refer to the current edition of 
the "IAB Official Protocol Standards" for the standardization state 
and status of this protocol. Distribution of this memo is unlimited. 


ABSTRACT 


The Simple Network Management Protocol (SNMP) [1] Distributed Program 
Interface (DPI) is an extension to SNMP agents that permits end-users 
to dynamically add, delete or replace management variables in the 
local Management Information Base without requiring recompilation of 
the SNMP agent. This is achieved by writing a so-called sub-agent 
that communicates with the agent via the SNMP-DPI. 


For the author of a sub-agent, the SNMP-DPI eliminates the need to 
know the details of ASN.1 [2] or SNMP PDU (Protocol Data Unit) 
encoding/decoding [1, 3]. 


This protocol has been in use within IBM since 1989 and is included 
in the SNMP agents for VM, MVS and OS/2. 


Potentially useful sample sub-agent code and implementation examples 
are available for anonymous FTP from the University of Toronto. 


MOTIVATION 


The Simple Network Management Protocol [1] defines a protocol that 


permits operations on a collection of variables. This set of 
variables is called the Management Information Base (MIB) and a core 
set of variables has previously been defined [4, 5]; however, the 


design of the MIB makes provision for extension of this core set. 
Thus, an enterprise or individual can define variables of their own 
which represent information of use to them. An example of a 
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potentially interesting variable which is not in the core MIB would 
be CPU utilization (percent busy). Unfortunately, conventional SNMP 
agent implementations provide no means for an end-user to make 
available new variables. 


The SNMP DPI addresses this issue by providing a light-weight 
mechanism by which a process can register the existence of a MIB 
variable with the SNMP agent. When requests for the variable are 
received by the SNMP agent, it will pass the query on to the process 
acting as a sub-agent. This sub-agent then returns an appropriate 
answer to the SNMP agent. The SNMP agent eventually packages an SNMP 
response packet and sends the answer back to the remote network 
management station that initiated the request. 


None of the remote network management stations have any knowledge 
that the SNMP agent calls on other processes to obtain an answer. As 
far as they can tell, there is only one network management 
application running on the host. 


THEORY OF OPERATION 
CONNECTION ESTABLISHMENT 


Communication between the SNMP Agent and its clients (sub-agents) 
takes place over a stream connection. This is typically a TCP 
connection, but other stream-oriented transport mechanisms can be 
used. As an example, the VM SNMP agent allows DPI connections over 
IUCV (Inter-User Communications Vehicle) [6, 7]. Other than the 
connection establishment procedure, the protocol used is identical in 
these environments. 


REGISTRATION 


Regardless of the connection-oriented transport mechanism used, after 
establishing a connection to the SNMP agent, the sub-agent registers 
the set of variables it supports. Finally, when all the variable 
classes have been registered, the sub-agent then waits for requests 
from the SNMP agent or generates traps as required. 


DPI ARCHITECTURE 


There are three requests that can be initiated by the SNMP agent: 
GET, GET-NEXT and SET. These correspond directly to the three SNMP 
requests that a network management station can make. The sub-agent 
responds to a request with a RESPONSE packet. 


There are currently two requests that can be initiated by a sub- 
agent: REGISTER and TRAP. 
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| SNMP Network | 
| Management Station | 


Ka sm ef ee == — så == kad 
A | Get A 
| | GetNext | GetResponse 
Trap | | Set | 
| v | 
Kee ee ee een en G * Km oe Se eee * 
| SNMP Protocol | | DPI Interface 
| EEE SER Reply | VERE | 
| ee | 
| SNMP Agent | | | | Client | 
| A kennen +-> | MIB query | | 
| | | Get/set á | |----------- >| | or | 
| Trap| info | SNMP | | | 
zseb +—==—===+=======% trap SNMP 
v | DPI <----------- Sub-Agent 
| TCP/IP layers, | | | | | | 
| Kernel | | |<----------- | | 
(eS a tn etn a karta eae * Register *----------=-------=----- * 
Figure 1. SNMP DPI overview 
Remarks for Figure 1: 
o The SNMP agent communicates with the SNMP manager via the 


standard SNMP protocol. 

o The SNMP agent communicates with the TCP/IP layers and kernel 
(operating system) in an implementation-dependent manner. It 
potentially implements the standard MIB view in this way. 

fe) An SNMP sub-agent, running as a separate process (potentially 
even on another machine), can register objects with the SNMP 
agent. 

o The SNMP agent will decode SNMP Packets. If such a packet 
contains a Get/GetNext or Set request for an object registered 
by a sub-agent, it will send the request to the sub-agent via 
the corresponding query packet. 

fe) The SNMP sub-agent sends responses back via a RESPONSE packet. 

fe) The SNMP agent then encodes the reply into an SNMP packet and 
sends it back to the requesting SNMP manager. 

fe) If the sub-agent wants to report an important state change, it 
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sends a TRAP packet to the SNMP agent, which will encode it 
into an SNMP trap packet and send it to the manager(s). 


SNMP DPI PROTOCOL 


This section describes the actual protocol used between the SNMP 
agent and sub-agents. This information has not previously been 
published. 


CONNECTION ESTABLISHMENT 


In a TCP/IP environment, the SNMP agent listens on an arbitrary TCP 
port for a connection request from a sub-agent. It is important to 
realize that a well-known port is not used: every invocation of the 
SNMP agent will potentially result in a different TCP port being 
used. 


A sub-agent needs to determine this port number to establish a 
connection. The sub-agent learns the port number from the agent by 
sending it one conventional SNMP get-request PDU. The port number 
is maintained by the SNMP agent as the object whose identifier is 
1.3.6.1.4.1.2.2.1.1.0; this variable is registered under the IBM 
enterprise-specific tree. The SNMP agent replies with a conventional 
SNMP response PDU that contains the port number to be used. This 
response is examined by the sub-agent and the port number is 
extracted. The sub-agent then establishes the connection to the 
specified port. 


On the surface, this procedure appears to mean that the sub-agent 
must be able to create and parse SNMP packets, but this is not the 
case. The DPI Application Program Interface (API) has a library 
routine, query DPI port(), which can be used to generate and parse 


the required SNMP packets. This routine is very small (under 100 
lines of C), so it does not greatly increase the size of any sub- 
agent). 


For completeness, byte-by-byte descriptions of the packets generated 
by the SNMP DPI API routine query_DPI_port() are provided below. 
This is probably of little interest to most readers and reading the 
source to query_DPI_port() provides much of the same information. 


SNMP PDU TO GET THE AGENT’S DPI PORT 


As noted, before a TCP connection to the SNMP agent can be made, the 
sub-agent must learn which TCP port that the agent is listening on. 
To do so, it can issue an SNMP GET for an IBM enterprise-specific 
variable 13.6, 41.22.1140 
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NOTE: the object instance of ".0" is included for clarity in this 
document. 


The SNMP PDU can be constructed as shown below. This PDU must be 


sent to UDP port 161 on the host where the agent runs (probably the 
same host where the sub-agent runs). 
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| Table 1. SNMP PDU for GET DPI port. This is the layout of an SNMP | 
| PDU for GET DPI_port | 


Fennen Fennen Fen + 
| OFFSET | VALUE | FIELD 
dennen Fennen Fe + 
| 0 | 0x30 | ASN.1 header 
Fennen Fennen Fe + 
| 1 | 34 + len | pdu_length, see formula below 
Fene Fennen nn Peet tr aen eh + 
| 2 | 0x02 0x01 0x00 | version (integer, length=1, | 

| 0x04 value=0), community name 

| (string) | 
Fennen Fennen Fen + 
| 6 | len | length of community name 
Fennen Fennen ads aa a + 
et | community name | | 
Fennen dee Fen + 
| 7 + len | Oxa0 Oxlb | SNMP GET request: 
| | | request_type=0xa0, length=0x1b | 
Fennen +—================ Fe + 

7 + len + 2 0x02 0x01 0x01 SNMP request ID: integer, 
length=1, ID=1 
Feen +—=-============== rm nnen rn ien mii + 
| 7 + len + 5 | 0x02 0x01 0x00 | SNMP error status: integer, | 
| | | length=1, error=0 | 
Feen Fennen ideen aa SEE FE aS Sea ae se Sse + 
7 + den +8 0x02 0x01 0x00 SNMP index: integer, length=1, 
index=0 

Fennen Fennen Fen + 
| 7 + len + 11 | 0x30 0x10 | Varbind list, length=0x10 
dennen dennen Fen + 
| 7 + len + 13 | 0x30 Ox0e | Varbind, length=0x0e 
Fennen Fennen Fen + 
| 7 + len + 15 | 0x06 Ox0a | Object ID, length=0x0a 
dennen Fennen Fe + 
| 7 + len + 17 | Ox2b 0x06 0x01 | Object instance: 

| 0x04 0x01 0x02 EE Zet 

| 0x02 0x01 0x01 | 
| | 0x00 | | 
Fennen Fennen Fen + 
| 7 + len + 27 | 0x05 0x00 | null value, length=0 
Fennen dee Fe + 
FDD + 


The formula to calculate the length field "pdu length" is as follows: 


pdu length = length of version field and string tag (4 bytes) 
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+ length of community length field (1 byte) 
+ length of community name (depends...) 
+ length of SNMP GET request (29 bytes) 


= 34 + length of community name 
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SNMP PDU CONTAINING THE RESPONSE TO THE GET 


Assuming that no errors occured, then the port is returned in the last 2 
octets of the received packet. The format of the packet is shown below: 


| Table 2. SNMP RESPONSE PDU for GET of Agent’s DPI port. This is the | 
| layout of an SNMP RESPONSE PDU for GET DPI_port 


Fennen Feen Fenn + 
| OFFSET | VALUE | FIELD | 
Fennen O Fe + 
18 | 0x30 | ASN.1 header 
Fennen +—================ Fenn + 
| 1 | 36 + len | length, see formula below 
Fennen Fennen Fen + 

2 0x02 0x01 0x00 version (integer, length=1, 

0x04 value=0), community name 

| | | (string) | 
Fennen Fennen Fe + 
| 6 | len | length of community name 
Fene Fennen Fenn + 
| 7 | community name | | 
dennen +—========= === å ED ET EE KE ska + 
| 7 + len | Oxa2 Oxld | SNMP RESPONSE: | 
| | | request_type=0xa2, length=0x1d | 
Fennen NEN A TETRA as me ca or ca ES E WS Ea mi E + 
| 7 + len + 2 | 0x02 0x01 0x01 | SNMP request ID: integer, | 
| | | length=1, ID=1 | 
Fene +—================ Fen + 
| 7 + len + 5 | 0x02 0x01 0x00 | SNMP error status: integer, | 
| | | length=1, error=0 | 
Fennen Fennen Fann A NE + 
| 7 + len + 8 | 0x02 0x01 0x00 | SNMP index: integer, length=1, | 
| | | index=0 | 
Fennen Fennen ene en ee ben en ne === + 
| 7 + len + 11 | 0x30 Ox12 | Varbind list, length=0x12 | 
Fene Fennen +—= === === == =—=——=——==———————————— === === + 
| 7 + len + 13 | 0x30 0x10 | Varbind, length=0x10 
p E === Fennen fa I NE nennen + 
| 7 + len + 15 | 0x06 Ox0a | Object ID, length=0x0a 
denn dee Fe + 
erdee hete eier eni earn haf enter eee ae eh ee + 


Carpenter & Wijnen [Page 8] 


RFC 1228 SNMP-DPI May 1991 


| Table 2. SNMP RESPONSE PDU for GET of Agent’s DPI port. This is the | 
| layout of an SNMP RESPONSE PDU for GET DPI_port 
4+----------------- 4+----------------- 
| OFFSET | 
4+----------------- 4+----------------- 
| 7 + len + 17 | 

| 


Object instance: | 
0x04 0x01 0x02 EE De Leda) | 


0x02 0x01 0x01 


| 
l 
| 
| 
| 
| 
| 
| 
| 
| 
| 
l 
| 
l 
| 
l 
l 
| 
| 
l 
l 
l 
| 
l 
l 
| 
| 
l 
l 
l 
| 
| 
| 
+ 


0x00 
Fenn Fenn ETE EEE HESTE ETER GEA AEE ES + 
| 7 + len + 27 | 0x02 0x02 | integer, length=2 
Fenn Fenn ——FV—mAAhmm '4vÆCÆÆvÆÆÆv/'' +42 mrs + 
| 7 + len + 29 | msb 1sb | port number (msb, lsb) | 
Fenn Fenn dale mede nn at An a + 
———NVvmJNm 7]. 2» masser + 


The formula to calculate the length field "pdu length" is as follows: 


pdu length length of version field and string tag (4 bytes) 
length of community length field (1 byte) 
length of community name (depends...) 


length of SNMP RESPONSE (31 bytes) 


++ + 


36 + length of community name 
SNMP DPI PACKET FORMATS 


Each request to or response from the agent is constructed as a 
"packet" and is written to the stream. 


Each packet is prefaced with the length of the data remaining in the 
packet. The length is stored in network byte order (most significant 
byte first, least significant last). The receiving side will read 
the packet by doing something similar to: 


unsigned char len_bfr[2]; 
char *bfr; 
int len; 


read(fd, len bfr,2); 

len = len bfr[0] * 256 + len bfr[l]; 
bfr = malloc(len); 

read(fd,bfr,len); 


NOTE: the above example makes no provisions for error handling or a 


read returning less than the requested amount of data. This is not a 
suggested coding style. 
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The first part of every packet identifies the application protocol 
being used, as well as some version information. The protocol major 
version is intended to indicate in broad terms what version of the 
protocol is used. The protocol minor version is intended to identify 
major incompatible versions of the protocol. The protocol release is 
intended to indicate incremental modifications to the protocol. The 
constants that are valid for these fields are defined in Table 10 on 
page 18. 


The next (common) field in all packets is the packet type. This 
field indicates what kind of packet we’re dealing with (SNMP DPI GET, 
GET-NEXT, SET, TRAP, RESPONSE or REGISTER). The permitted values for 
this field are defined in Table 11 on page 18. 


rine a a a a trier nnee ser ne ee ee EE TEKE ES EG + 

Table 3. SNMP DPI packet header. This header is present in all 
packets. 

Feen FDD. + 

| OFFSET | FIELD | 

Fee FDD. + 

| 0 | packet length to follow (MSB) 

Fene FDT + 

| 1 | packet length to follow (LSB) 

Fen FDT + 

| 2 | protocol major version 

Fene beenen ee trien ne ans === are == == + 

| 3 | protocol minor version 

Fene FDT + 

| 4 | protocol release 

Fee FDT + 

ES: | packet type 

dee ener Be nennen eere ern er ee E + 

ne ie === =———— == — == — == == — == == — == — == s — === == == — == === === == === === == == === + 


>From this point onwards, the contents of the packet are defined by the 
protocol being used. The remainder of this section describes: 


(0) the structure of packets for the SNMP DPI protocol, version 1.0. 


o The constants as defined with this version of the protocol. 
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REGISTER 


In order to register a branch in the MIB tree, an SNMP sub-agent 
sends an SNMP DPI REGISTER packet to the agent. 


Such a packet contains the standard SNMP DPI header plus REGISTER- 
specific data, which basically is a null terminated string 
representing the object ID in dotted ASN.1 notation (with a trailing 
dot!). 


| Table 4. SNMP DPI REGISTER packet. This is the layout of an SNMP | 
| DPI REGISTER packet 


+------------- 4-------------------------------------------------------- + 
| OFFSET | FIELD | 
+------------- 4-------------------------------------------------------- + 
| o | packet length to follow (MSB) 

4+------------- 4-------------------------------------------------------- + 
| | packet length to follow (LSB) 

4+------------- 4-------------------------------------------------------- + 
| 2 | protocol major version 

+------------- 4-------------------------------------------------------- + 
|3 | protocol minor version 

+------------- 4+-------------------------------------------------------- + 
| 4 | protocol release 

+------------- 4-------------------------------------------------------- + 
|5 | packet type = SNMP_DPI_REGISTER 

+------------- 4-------------------------------------------------------- + 
| 6 | null terminated object ID 

4+------------- 4+-------------------------------------------------------- + 
4+---------------------------------------------------------------------- + 
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GET 


When the SNMP agent receives a PDU containing an SNMP GET request for 
a variable that a sub-agent registered with the agent, it passes an 
SNMP DPI GET packet to the sub-agent. 


Such a packet contains the standard SNMP DPI header plus GET-specific 
data, which is basically a null terminated string representing the 
object ID in dotted ASN.1 notation. 


$------- $$ 5 5 + 
| Table 5. SNMP DPI GET packet. This is the layout of an SNMP DPI GET | 
| packet | 
+------------- +-======================——==—====—=—======—========—==———======== + 
| OFFSET | FIELD | 
+============= +-=========================—===—=—=—=—==—===—========—=————======== + 
| 0 | packet length to follow (MSB) 

+-============ +-====================================—========—=—=——======== + 
ler | packet length to follow (LSB) 

+-============ +-============================—==—======—========—=——=——======== + 
| 2 | protocol major version 

+------------- +===============================—======—==========—=—======== + 
| 3 | protocol minor version 

+-============ +-==============================—===============—=—=—======== + 
| 4 | protocol release 

+============= +-============================—==—======—==========—=——======== + 
| 5 | packet type = SNMP_DPI_GET | 
+------------- +-======================—===—===—==—===—===—=========—=—=—======== + 
| 6 | null terminated object ID 

+-============ +-===================—=================—==—======—=—=——======== + 
$------------ $$ 5 ennn eenen + 
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GET-NEXT 


When the SNMP agent receives a PDU containing an SNMP GET-NEXT 


request for a variable for which a sub-agent may be authoritative, it 


passes an SNMP DPI GET-NEXT packet to the sub-agent. 


Such a packet contains the standard SNMP DPI header plus GET-NEXT- 
specific data. These data take the form of two null terminated 

strings. The first string represents the object ID in dotted ASN.1 
notation; the second string represents the group ID in dotted ASN.1 


notation. 
+ ——— — — — — == — == = = = = — — — — — — — — — — — — — — — 
| Table 6. SNMP DPI GET NEXT packet. This is the layout of an SNMP 
| DPI GET NEXT packet 
Fen hoe RAS Sessa SRS a ea Ss Se as ee a ease ees + 
| OFFSET | FIELD 
Fene FDT + 
| 0 | packet length to follow (MSB) 
Fene ane E == == — === == === == == — === == === === === === + 
lt | packet length to follow (LSB) 
Fene FDT + 
2 | protocol major version 
Fee FDD. + 
(3 | protocol minor version 
Fene aa ier ait ennen eea ET icm as SEE re ie ae + 
| 4 | protocol release 
Fee fa nn O T A + 
lee | packet type = SNMP_DPI_GET_NEXT 
Fen FDD. + 
| 6 | null terminated object ID 
Fene ken ae en lei kred pe nn == — === == === == === == == + 
| 6 + len | null terminated group ID 
Fene FDD. + 
| NOTE: len=strlen(object ID)+1 
+ =-= — — == == = = = = = — — — — — — — — — — — — 
+ —-—-—— — — — — === — == = = = —= — — — — — — — — — — — — — — — 
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SET 


When the SNMP agent receives a PDU containing an SNMP SET request for 
a variable that a sub-agent registered with the agent, it passes an 
SNMP DPI SET packet to the sub-agent. 


Such a packet contains the standard SNMP DPI header plus SET specific 
data, which is basically a null terminated string representing the 

object ID in ASN.1 notation, with the type, value length and value to 
be set. The permitted types for the type field are defined in Table 


12 on page 19. Integer values are sent as 4-byte elements in network 

byte order (most significant byte first, least significant byte 

last). 
be a ee ee ee ee + 

Table 7. SNMP DPI SET packet. This is the layout of an SNMP DPI SET 
packet 

Fene FDT + 
| OFFSET | FIELD | 
Fee MF em se ie rs Se + 
| 0 | packet length to follow (MSB) 
Fene FDD. + 
| 1 | packet length to follow (LSB) 
Fen FDD. + 
[2 | protocol major version 
Fene beenen ee trien ne ann ns === re === == + 
| 3 | protocol minor version 
Fene FDT + 
| 4 | protocol release 
Fee FDD. + 
135 | packet type = SNMP DPI SET | 
Fene Fn nn EE EA E + 
| 6 | null terminated object ID 
Fene FDT + 
| 6 + len | SNMP Variable Type Value 
Fene fa nn E a E a AS + 
| 6 + len + 1 | Length of value (MSB) | 
dee hoe eae SS ra reker seen ensen + 
| 6 + len + 2 | Length of value (LSB) | 
Fene FDT + 
| 6 + len + 3 | Value | 
+—============ FDD + 
| NOTE: len=strlen(object ID) +1 | 
Fn nn T O A AA + 
FDD + 
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RESPONSE 


An SNMP sub-agent must respond to a GET, GET NEXT or SET request that 
it has received from the agent (unless it fails or has a bug). To do 
so, it sends an SNMP DPI RESPONSE packet to the agent. 


Such a packet contains the standard SNMP DPI header plus RESPONSE 
specific data, which basically is an error code plus (if there was no 
error), the name/type/value tuple representing the returned object. 
This is described as by a string representing the object ID in ASN.1 
notation, plus the type, value length and value of the object that 
was manipulated. The permitted types for the type field are defined 


in Table 12 on page 19. Integer values are sent as 4-byte elements 
in network byte order (most significant byte first, least significant 
byte last). 
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| Table 8. SNMP DPI RESPONSE packet. This is the layout of an SNMP | 
| DPI RESPONSE packet 


+------------- 4-------------------------------------------------------- + 
| OFFSET | FIELD | 
4+------------- 4-------------------------------------------------------- + 
| o | packet length to follow (MSB) 

4+------------- 4-------------------------------------------------------- + 
| 1 | packet length to follow (LSB) 

4+------------- 4-------------------------------------------------------- + 
| 2 | protocol major version 

+------------- 4-------------------------------------------------------- + 
| 3 | protocol minor version 

4+------------- 4+-------------------------------------------------------- + 
| 4 | protocol release 

+------------- 4+-------------------------------------------------------- + 
|5 | packet type = SNMP_DPI_RESPONSE 

+------------- 4-------------------------------------------------------- + 
| 6 | SNMP error code 

4+------------- 4-------------------------------------------------------- + 
|7 | null terminated object ID 

+------------- 4-------------------------------------------------------- + 
| 7 + len | SNMP Variable Type Value 

4+------------- 4+-------------------------------------------------------- + 
| 7 + len + 1 | Length of value (MSB) 

+------------- 4+-------------------------------------------------------- + 
| 7 + len + 2 | Length of value (LSB) 

4+------------- 4$-------------------------------------------------------- + 
| 7 + len + 3 | Value | 
+------------- 4+-------------------------------------------------------- + 
| NOTE: len=strlen(object ID)+1 
4+----------------------------------------------- === === === == === === === === + 
4---------------------------------------------- === === === === === --------- + 
TRAP 


An SNMP sub-agent can request the agent to generate a TRAP by sending 
an SNMP DPI TRAP packet to the agent. 


Such a packet contains the standard SNMP DPI header plus TRAP 
specific data, which is basically the generic and specific trap code, 
plus a name/type/value tuple. The tuple is described by a string 
representing the object ID in ASN.1 notation, plus the type, value 
length and value of the object that is being sent in the trap. The 
permitted types for the type field are defined in Table 12 on page 
19. Integer values are sent as 4-byte elements in network byte order 
(most significant byte first, least significant byte last). 
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+-====================== === === === === === == === === === === === === === === === + 
Table 9. SNMP DPI TRAP packet. This is the layout of an SNMP DPI | 
TRAP packet | 
4+------------- 4-------------------------------------------------------- + 
| OFFSET | FIELD | 
4+------------- 4-------------------------------------------------------- + 
| o | packet length to follow (MSB) 
4+------------- 4-------------------------------------------------------- + 
| 1 | packet length to follow (LSB) 
4+------------- 4-------------------------------------------------------- + 
| 2 | protocol major version 
+------------- 4-------------------------------------------------------- + 
| 3 | protocol minor version 
4+------------- 4+-------------------------------------------------------- + 
| 4 | protocol release 
+------------- 4$-------------------------------------------------------- + 
|5 | packet type - SNMP_DPI_TRAP | 
+------------- 4-------------------------------------------------------- + 
| 6 | SNMP generic trap code 
4+------------- 4-------------------------------------------------------- + 
|7 | SNMP specific trap code 
+------------- +-=========================================—=—————=—=——=—=—== + 
| 8 | null terminated object ID 
+-============ 4+-------------------------------------------------------- + 
| 8 + len | SNMP Variable Type Value 
4+------------- 4-------------------------------------------------------- + 
| 8 + len + 1 | Length of value (MSB) | 
4+------------- 4+-------------------------------------------------------- + 
| 8 + len + 2 | Length of value (LSB) | 
4+------------- 4+-------------------------------------------------------- + 
| 8 + len + 3 | Value | 
4+------------- 4+-------------------------------------------------------- + 
| NOTE: len=strlen(object ID) +1 | 
4+---------------------------------------------------------------------- + 
4$-------------------------------------------------- === === === == --------- + 


Carpenter & Wijnen 


[Page 17] 


RFC 1228 SNMP-DPI May 1991 


CONSTANTS AND VALUES 


This section describes the constants that have been defined for this 
version of the SNMP DPI Protocol. 


PROTOCOL VERSION AND RELEASE VALUES 


Mental talte A kr servere tr arrest bre ee oe arr ar fetest + 
| Table 10. Protocol version and release values 
FDD a E + 
| FIELD | VALUE | 
FDD Fr + 
| protocol major version | 2 (SNMP DPI protocol) 
FDD FDD + 
| protocol minor version | 1 (version 1) 
FDD Fr + 
| protocol release | 0 (release 0) 
nen ain ane a an ian he ans FDD + 
FDD. + 
Any other values are currently undefined. 
PACKET TYPE VALUES 

The packet type field can have the following values: 
FDD. + 
| Table 11. Valid values for the packet type field | 
Fenn tone ae a ee EVE eedt eet mc ee mene Ene + 
| VALUE | PACKET TYPE | 
Fenn stek de ke te oe ko sed ee SS Se + 
|1 | SNMP_DPI_GET | 
Fenn ea SSK SONE ES eee ende stein setes che nietde ene + 
| 2 | SNMP_DPI_GET_NEXT | 
Fenn FDD. + 
| 3 | SNMP_DPI_SET | 
Fenn Fr. + 
| 4 | SNMP DPI TRAP | 
Fenn Pn R S + 
|5 | SNMP_DPI_RESPONSE | 
Fenn FTD + 
| 6 | SNMP DPI REGISTER | 
Fenn PS Sa a a ee ee ee eee + 
PS E E + 
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VARIABLE TYPE VALUES 


The variable type field can have the following values: 


number (integer) | 


empty (no value) | 


counter (unsigned) | 


gauge (unsigned) | 


NOTE: Fields which represent values that are stored as a 4-byte 
integer are indicated by ORing their base type value with 128. 


Error Code Values for SNMP Agent Detected Errors 


The error code can have one of the following values: 
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| Table 13. Valid values for the SNMP Agent Minor Error Code field | 

de FDD + 
SNMP AGENT ERROR CODE 

—-—-— — — — — — iii iii iii iii + 
no error | 


| 

+ 

| 

+ 

| 

+ 

| no such name | 
dee 4-------------------------------------------------------------- + 

| bad value | 

Fennen + 

| read only | 

+— === + 

| general error | 

+ 


SNMP DPI APPLICATION PROGRAM INTERFACE 


This section documents an API that implements the SNMP DPI. This 
information has been previously published [6, 8], but the information 
provided below is more current as of May 14, 1991. 


OVERVIEW OF REQUEST PROCESSING 
GET PROCESSING 
A GET request is the easiest to process. When the DPI packet is 
parsed, the parse tree holds the object ID of the variable being 
requested. 
If the specified object is not supported by the sub-agent, it would 
return an error indication of "no such name". No name/type/value 
information would be returned. 
unsigned char *cp; 
cp = mkDPIresponse (SNMP_NO_SUCH_NAME, 0) ; 
If the object is recognized, then the sub-agent creates a parse tree 
representing the name/type/value of the object in question (using the 


DPI API routine mkDPIset()), and returns no error indication. This 
is demonstrated below (a string is being returned). 
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char *obj id; 


unsigned char *cp; 
struct dpi set packet *ret value; 
char *data; 


/* obj id = object ID of variable, like 1.3.6.1.2.1.1.1 */ 

/* should be identical to object ID sent in get request */ 

data = "a string to be returned"; 

ret value = mkDPIset (obj id, SNMP TYPE STRING, 
strlen(data)+l,data); 

cp = mkDPIresponse(0,ret value); 


SET PROCESSING 


Processing a SET request is only slightly more difficult than a GET 
request. In this case, additional information is made available in 
the parse tree, namely the type, length and value to be set. 


The sub-agent may return an error indication of "no such name" if the 
variable is unrecognized, just as in a GET request. If the variable 
is recognized, but cannot be set, an error indication of "no such 
name" should be also be returned, although it is tempting to return a 
"read only" error. 


GET NEXT PROCESSING 


GET-NEXT requests are the most complicated requests to process. 
After parsing a GET-NEXT request, the parse tree will contain two 
parameters. One is the object ID on which the GET-NEXT operation is 
being performed. The semantics of the operation are that the sub- 
agent is to return the name/type/value of the next variable it 
supports whose name lexicographically follows the passed object ID. 


It is important to realize that a given sub-agent may support several 
discontiguous sections of the MIB tree. In such a situation it would 
be incorrect to jump from one section to another. This problem is 
correctly handled by examining the second parameter which is passed. 
This parameter represents the "reason" why the sub-agent is being 
called. It holds the prefix of the tree that the sub-agent had 
indicated it supported. 


If the next variable supported by the sub-agent does not begin with 
that prefix, the sub-agent must return an error indication of "no 
such name". If required, the SNMP agent will call upon the sub-agent 
again, but pass it a different group prefix. This is illustrated in 
the discussion below: 
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Assume there are two sub-agents. The first sub-agent registers two 
distinct sections of the tree, A and C. In reality, the sub-agent 
supports variables A.1 and A.2, but it correctly registers the 
minimal prefix required to uniquely identify the variable class it 
supports. 


The second sub-agent registers a different section, B, which appears 
between the two sections registered by the first agent. 


If a remote management station begins dumping the MIB, starting from 
A, the following sequence of queries would be performed: 


Sub-agent 1 gets called: 


get-next (A,A) == A.1 
get-next (A.1,A) = A.2 
get-next (A.2,A) = error(no such name) 


Sub-agent 2 is then called: 
get-next (A.2,B) = B.1 
get-next (B.1,B) = error(no such name) 


Sub-agent 1 gets called again: 
get-next (B.1,C) = C.1 


REGISTER REQUESTS 


A sub-agent must register the variables it supports with the SNMP 
agent. The appropriate packets may be created using the DPI API 
library routine mkDPIregister(). 


unsigned char *cp; 
cp = mkDPIregister("1.3.6.1.2.1.1.2."); 
NOTE: object IDs are registered with a trailing dot ("."). 
TRAP REQUESTS 
A sub-agent can request that the SNMP agent generate a trap for it. 
The sub-agent must provide the desired values for the generic and 
specific parameters of the trap. It may optionally provide a 
name/type/value parameter that will be included in the trap packet. 


The DPI API library routine mkDPItrap() can be used to generate the 
required packet. 
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DPI API LIBRARY ROUTINES 
This section documents Application Program Interfaces to the DPI. 
QUERY DPI PORT (0) 


int port; 
char *hostname, *community name; 


port = query DPI port (hostname, community name); 
The query DPI port() function is used by a DPI client to determine 
what TCP port number is associated with the DPI. This port number is 


needed to connect() to the SNMP agent. If the port cannot be 
determined, -1 is returned. 


The function is passed two arguments: a string representing the 
host”s name or IP address and the community name to be used when 
making the request. 


This function enables a DPI client to "bootstrap" itself. The port 
number is obtained via an SNMP GET request, but the DPI client does 
not have to be able to create and parse SNMP packets--this is all 
done by the query DPI port() function. 


NOTE: the query DPI port() function assumes that the community name 
does not contain any null characters. If this is not the case, use 
the query DPI port() function which takes a third parameter, the 
length of the community name. 
MKDPIREGISTER 
#include "snmp dpi.h" 


unsigned char *packet; 
int len; 


/* register sysDescr variable */ 
packet = mkDPIregister("1.3.6.1.2.1.1.1."); 


len = *packet * 256 + *(packet + 1); 
len += 2; /* include length bytes */ 


The mkDPIregister() function creates the necessary register-request 
packet and returns a pointer to a static buffer holding the packet 
contents. The null pointer (0) is returned if there is an error 


detected during the creation of the packet. 
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The length of the remainder packet is stored in the first two bytes 
of the packet, as demonstrated in the example above. 


NOTE: object identifiers are registered with a trailing dot ("."). 
MKDPISET 
#include "snmp dpi.h" 
struct dpi set packet *set value; 


char *obj id; 
int type, length; 
char *value; 


set value = mkDPIset (obj id, type, length, value); 


The mkDPIset() function can be used to create the portion of a parse 
tree that represents a name/value pair (as would be normally be 
returned in a response packet). It returns a pointer toa 
dynamically allocated parse tree representing the name/type/value 
information. If there is an error detected while creating the parse 
tree, the null pointer (0) is returned. 


The value of type can be one of the following (which are defined in 
the include file "snmp_dpi.h"): 


SNMP TYPE NUMBER 
SNMP TYPE STRING 
SNMP TYPE OBJECT 
SNMP TYPE INTERNET 
SNMP TYPE COUNTER 
SNMP TYPE GAUGE 
SNMP TYPE TICKS 


00000006 


The value parameter is always a pointer to the first byte of the 
object’s value. 


NOTE: the parse tree is dynamically allocated and copies are made of 
the passed parameters. After a successful call to mkDPIset(), they 
can be disposed of in any manner the application chooses without 
affecting the parse tree contents. 
MKDPIRESPONSE 
#include "snmp dpi.h" 


unsigned char *packet; 
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int error code; 
struct dpi set packet *ret value; 


packet = mkDPIresponse(error code, ret value); 


len = *packet * 256 + *(packet + 1); 
len += 2; /* include length bytes */ 


The mkDPIresponse() function creates an appropriate response packet. 


It takes two parameters. The first is the error code to be returned. 


It may be 0 (indicating no error) or one of the following (which are 
defined in the include file "snmp dpi.h"): 


SNMP_NO_ERROR 
SNMP_TOO_BIG 
SNMP_NO_SUCH_NAME 
SNMP_BAD_VALUE 
SNMP_READ_ONLY 
SNMP_GEN_ERR 


000000 


If the error code indicates no error, then the second parameter is a 
pointer to a parse tree (created by mkDPIset()) which represents the 
name/type/value information being returned. If an error is 

indicated, the second parameter is passed as a null pointer (0). 


If the packet can be created, a pointer to a static buffer containing 


the packet contents is returned. This is the same buffer used by 
mkDPIregister(). If an error is encountered while creating the 
packet, the null pointer (0) is returned. 


The length of the remainder packet is stored in the first two bytes 
of the packet, as demonstrated in the example above. 


NOTE: mkDPIresponse() always frees the passed parse tree. 
MKDPITRAP 
#include "snmp dpi.h" 
unsigned char *packet; 


int generic, specific; 
struct dpi set packet *ret value; 


packet = mkDPItrap(generic, specific, ret value); 


len = *packet * 256 + *(packet + 1); 
len += 2; /* include length bytes */ 
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The mkDPItrap() function creates an appropriate trap request packet. 
The first two parameters correspond to to value of the generic and 
specific fields in the SNMP trap packet. The third field can be used 
to pass a name/value pair to be provided in the SNMP trap packet. 
This information is passed as the set-packet portion of the parse 
tree. As an example, a linkDown trap for interface 3 might be 
generated by the following: 


struct dpi_set_packet *if_index_value; 
unsigned long data; 

unsigned char *packet; 

int len; 


data = 3; /* interface number = 3 */ 

if index value = mkDPIset("1.3.6.1.2.1.2.2.1.1", SNMP TYPE NUMBER, 
sizeof (unsigned long), &data); 

packet = mkDPItrap(2, 0, if index value); 

len = *packet * 256 + *(packet + 1); 

len += 2; /* include length bytes */ 

write(fd,packet,len); 


If the packet can be created, a pointer to a static buffer containing 
the packet contents is returned. This is the same buffer used by 
mkDPIregister(). If an error is encountered while creating the 
packet, the null pointer (0) is returned. 


The length of the remainder packet is stored in the first two bytes 
of the packet, as demonstrated in the example above. 


NOTE: mkDPItrap() always frees the passed parse tree. 
PDPIPACKET 

#include "snmp dpi.h" 

unsigned char *packet; 

struct snmp dpi hdr *hdr; 

hdr = pDPIpacket (packet) 
The pDPIpacket() function parses a DPI packet and returns a parse 
tree representing its contents. The parse tree is dynamically 
allocated and contains copies of the information within the DPI 
packet. After a successful call to pDPIpacket(), the packet may be 
disposed of in any manner the application chooses without affecting 


the contents of the parse tree. If an error is encountered during 
the parse, the null pointer (0) is returned. 
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NOTE: the relevant parse tree structures are defined in the include 
file "snmp dpi.h", and that file remains the definitive reference. 


The root of the parse tree is represented by a snmp dpi hdr 
structure: 


struct snmp dpi hdr { 
unsigned char proto major; 
unsigned char proto minor; 
unsigned char proto release; 


unsigned char packet type; 


union ( 
struct dpi get packet *dpi get; 
struct dpi next packet *dpi next; 
struct dpi set packet *dpi set; 
struct dpi resp packet *dpi response; 


struct dpi trap packet *dpi trap; 
} packet body; 
}; 


The field of immediate interest is packet_type. This field can have 
one of the following values (which are defined in the include file 
"snmp dpi.h"): 


Oo SNMP DPI GET 
Oo SNMP DPI GET NEXT 
Oo SNMP DPI SET 


The packet type field indicates what request is being made of the DPI 
client. For each of these requests, the remainder of the packet body 
will be different. 


If a get request is indicated, the object ID of the desired variable 
is passed in a dpi_get_packet structure: 


struct dpi_get_packet { 
char *object_id; 
}; 


A get-next request is similar, but the dpi_next_packet structure also 
contains the object ID prefix of the group that is currently being 
traversed: 


struct dpi_next_packet { 
char *object id; 
char *group id; 

}; 
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If the next object whose object ID lexicographically follows the 
object ID indicated by object id does not begin with the suffix 
indicated by group id, the DPI client must return an error indication 
of SNMP NO SUCH NAME. 


A set request has the most amount of data associated with it and this 
is contained in a dpi set packet structure: 


struct dpi set packet { 
char *object id; 
unsigned char type; 
unsigned short value len; 
char *value; 


}; 


The object ID of the variable to be modified is indicated by 
object_id The type of the variable is provided in type and may have 
one of the following values: 


NMP_TYPE_NUMBER 
MP_TYPE_STRING 
MP_TYPE_OBJECT 
MP_TYPE_EMPTY 

MP TYPE INTERNET 
MP TYPE COUNTER 
MP TYPE GAUGE 
MP TYPE TICKS 


000000006 
ANNNNNHNN 
22222224 


The length of the value to be set is stored in value_len and value 
contains a pointer to the value. 


NOTE: the storage pointed to by value will be reclaimed when the 
parse tree is freed. The DPI client must make provision for copying 
the value contents. 
FDPIPARSE 

#include "snmp dpi.h" 

struct snmp dpi hdr *hdr; 

fDPIparse (hdr); 
The routine fDPIparse() frees a parse tree previously created by a 
call to pDPIpacket This routine is declared as void--it has no return 


value. 


NOTE: after calling fDPIparse(), no further references to the parse 
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tree can be made. 
AGENT IMPLEMENTATION ISSUES 


Although the SNMP DPI protocol is completely documented in this 
paper, the document itself is somewhat biased towards clearly 
defining the interface provided to sub-agents (i.e., it provides a 
specification of a C language API). This detailed coverage is 
possible because the client side of the interface is completely 
self-contained. 


The agent side of the interface has to be integrated into individual 
vendor implementations, many of which may have a unique 
organizational structure in an attempt to address various performance 
and storage constraints. This makes it infeasible to provide much 
more than suggestions for SNMP agent implementers. Unfortunately, 
this leaves room for a large amount of interpretation which can lead 
to implementations that don’t necessarily work they way they should- 
-too much ambiguity can be a bad thing. 


The following characteristics of an agent implementation are to be 
considered mandatory: 


DUPLICATE REGISTRATIONS 


With this release of the protocol, order of registration is 
significant. The last sub-agent to register a variable is the one 
that is deemed to be authoritative. Variables implemented by the 
base SNMP agent are considered to have been registered prior to any 
sub-agent registrations. Thus sub-agents may re-implement support 
for variables that were incorrectly implemented by a vendor. 


AUTOMATIC DEREGISTRATION ON CLOSE 


All SNMP DPI connections are carried over a stream connection. When 
the connection is closed by the client (no matter what the cause), 
the agent must automatically unregister all of the variables that 
were registered by the sub-agent. 


TIMELY RESPONSE CONSTRAINTS 


A sub-agent must respond to a request in a timely fashion. In this 
version of the protocol, we specify that a sub-agent must respond to 
a request by the SNMP agent within 5 seconds. If the sub-agent does 
not respond in time, the SNMP agent should terminate the connection 
and unregister all of the variables that were previously registered 
by the sub-agent in question. 
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NOTE: agent implementations that do not have access to a timer may 
not be able to implement this. In that case, they leave themselves 
open to being placed in a state where they are blocked forever if the 
sub-agent malfunctions. 


SUPPORT FOR MULTIPLE MIB VIEWS 


Some agents allow different MIB views to be selected based on the 
community name used. It is not the intention of this document to 
pass judgement on the various approaches that have been proposed or 
implemented, but instead merely to recognize the existence of 
implementations that support this feature. 


The point of this discussion is to specify clearly that objects 
supported by an SNMP DPI sub-agent are to be registered under the MIB 
view that was selected by the community name used in the SNMP GET 
request that obtained the DPI port value. 


The SNMP DPI does not specify a reserved port, but instead sub-agents 
bootstrap themselves by making an SNMP GET request for the DPI port 
variable. This variable represents the TCP port to which the sub- 
agent should connect. It should be understood that there is no 
reason why the SNMP agent cannot have several listens (passive opens) 
active, each corresponding to a distinct MIB view. The port number 
returned then would be different based on the community name used in 
the SNMP GET request for the DPI port variable. 


CONSIDERATIONS FOR THE NEXT RELEASE 


The SNMP DPI protocol makes provision for extension and parallel use 
of potentially incompatible releases. The discussion above documents 
the protocol as it is currently in use and has not discussed features 
of interest that should be considered for a future revision. 
UNREGISTER 
For closure, an UNREGISTER request could be of use. 
SUPPORT FOR ATOMIC SETS 
The SNMP protocol [1] specifies that: 
Each variable assignment specified by the SetRequest-PDU should be 
effected as if simultaneously set with respect to all other 


assignments specified in the same message. 


The SNMP DPI has no provision for backing out a successfully 
processed SET request if one of the subsequent variable assignments 
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fails. This omission is a reflection of several biases: 


[0] 


[0] 


the SNMP DPI was intended to be light-weight. 


a belief that the SNMP RFC prescribes semantics which are infeasible 
to implement unless the range of applications is restricted. 


It has been suggested that a new request, TEST SET, be added to the 


DPI protocol. Processing of a SET request would then be performed as 

follows: 

fe) all variables would be processed using TEST_SET unless any error 
occurred. The subagents would verify that they could process the 
request. 

(0) if no error occurred, each of the variables would be reprocessed, 


this time with a SET request. 


A problem with such an approach is that it relies on the TEST_SET 
operation to make an assertion that the request can be successfully 
performed. If this is not possible, then it cannot be asserted that 
the prescribed semantics will be provided. Such situations do exist, 
for example, a SET request that causes the far-end channel service 
unit to be looped up--one does not know if the operation will be 
successful until it is performed. 


SAMPLE SNMP DPI API IMPLEMENTATION 


The following C language sources show an example implementation of 
the SNMP DPI Application Programming Interface as it would be exposed 
to the sub-agents. 


SAMPLE SNMP DPI INCLUDE FILE 


/* SNMP distributed program interface */ 


#define SNMP_DPI_GET 1 
#define SNMP_DPI_GET_NEXT 2 
#define SNMP_DPI_SET 3 
#define SNMP_DPI_TRAP 4 
#define SNMP_DPI_RESPONSE 5 
#define SNMP_DPI_REGISTER 6 
#define SNMP_DPI_PROTOCOL 2 
#define SNMP_DPI_VERSION 1 
#define SNMP_DPI_RELEASE 0 


/* SNMP error codes from RFC 1098 (1067) */ 
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#define 
#define 
#define 
#define 
#define 
#define 
/* vari 
#define 
#define 
#define 
#define 
#define 
#define 
#define 
#define 
#define 
#define 


struct 


}; 


struct 


pr 


struct 


I; 


struct 


}; 


struct 


}; 


struct 


SNMP-DPI 


NMP NO ERROR 

MP TOO BIG 

MP NO SUCH NAME 
MP BAD VALUE 

MP READ ONLY 

MP GEN ERR 


ANNNNN 
222202 


able types */ 

NMP TYPE TEXT 
NMP TYPE NUMBER 
MP TYPE STRING 
MP TYPE OBJECT 
MP TYPE EMPTY 
MP TYPE INTERNET 
MP TYPE COUNTER 
MP TYPE GAUGE 
MP TYPE TICKS 
MP TYPE MASK 


S 
S 
S 
S 
S 
S 
S 
S 
S 
S 


2222222424 


dpi_get_packet { 
char *object id; 


dpi next packet { 
char *object id; 
char *group id; 


dpi set packet { 


char *object_ 


unsigned char type; 


OP WNHR O 


id; 


unsigned short value_len; 


char *value; 


dpi_resp_packet { 


unsigned char ret_code; 
*ret_data; 


struct dpi_set_packet 


dpi_trap_packet { 
unsigned char generic; 


unsigned char specific; 


struct dpi_set_packet 


snmp_dpi_hdr { 
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*info; 


/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
/* 
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textual representation */ 
number */ 

text string */ 

object identifier */ 

no value */ 

internet address */ 

counter */ 

gauge */ 

time ticks (1/100th sec) */ 
mask for type */ 
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}; 


extern 
extern 
extern 
extern 
extern 
extern 
extern 


SAMPLE QUE 


unsigned char 
unsigned char 
unsigned char 


unsigned char 
union { 
struct 
struct 
struct 
struct 
struct 
} packet_body; 


RY_DPI_PORT () 


#ifdef VM 


#include 
#include 
#include 
#include 
#include 
#include 
#include 
#include 


#else 


#include 
#include 
#include 
#include 
#include 
#include 


#endif 


static unsigned char asni_hdr[] = 


Carpenter 


<manifest.h> 
<snmp_vm. h> 
<bsdtime.h> 
<bsdtypes.h> 
<socket.h> 
<in.h> 
<netdb.h> 
<inet.h> 


<sys/time.h> 
<sys/types.h> 


SNMP-DPI 


proto major; 
proto minor; 
proto release; 


packet type; 


dpi get packet 
dpi next packet 
dpi set packet 
dpi resp packet 
dpi trap packet 


struct snmp dpi hdr *pDPIpacket 
void fDPIparse(); 

unsigned char *mkMIBquery () ; 
unsigned char *mkDPIregister(); 
unsigned char *mkDPIresponse() ; 
unsigned char *mkDPItrap(); 
struct dpi set packet *mkDPIset(); 


FUNCTION 


<sys/socket.h> 
<netinet/in.h> 


<netdb.h> 
<arpa/inet.h> 


& Wijnen 


~ 


); 


{0x30}; 


May 1991 
*dpi get; 
*dpi next; 
*dpi set; 
*dpi response; 
*dpi trap; 
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/* insert length of remaining packet, not including this */ 
static unsigned char version[] = {0x02, 0x01, 0x00, 0x04}; 


/* integer, len=1, value=0, string */ 

/* insert community name length and community name */ 

static unsigned char request[] = { 
Oxa0, Oxlb, /* get request, len=0x1b */ 
0x02, 0x01, 0x01, /* integer, len=1,request_id = 1 */ 
0x02, 0x01, 0x00, /* integer, len=1, error status = 0 */ 


0x02, 0x01, 0x00, /* integer, len=1, error_index = 0 */ 
0x30, 0x10, /* varbind list, len=0x10 */ 
0x30, Ox0e, /* varbind , len=0x0e */ 
0x06, O0x0a, /* object ID, len=0x0a */ 
0x2b, 0x06, 0x01, 0x04, 0x01, 0x02, 0x02, 0x01, 0x01, 0x00, 
0x05, 0x00 /* value, len = 0 */ 

}; 

static extract_DPI_port(); 


query_DPI_port (hostname, community_name) 


char *hostname; 
char *community_name; 
{ 
int community len; 
int re; 
community_len = strlen(community_name) ; 
rc = query DPI port (hostname, community name, community len); 


return (rc); 


) 
/* use if community name has embedded nulls */ 


query DPI port (hostname, community name, community len) 
char *hostname; 
char *community name; 
int community len; 
{ 
unsigned char packet [1024]; 


int packet_len; 
int remaining_len; 
int fd, rc, sock_len; 


struct sockaddr_in sock, dest_sock; 
struct timeval timeout; 

unsigned long host_addr, read_mask; 
int tries; 
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host addr = lookup host (hostname); 

packet len = 0; 

bcopy (asnl hdr, packet, sizeof(asnl hdr)); 
packet len += sizeof (asnl hdr); 


remaining len = sizeof (version) + 1 + 
community len + sizeof (request); 


packet [packet len++] = remaining len & Oxff; 

bcopy (version, packet + packet len, sizeof (version)); 
packet len += sizeof (version); 

packet [packet len++] = community len & Oxff; 

bcopy (community name, packet + packet len, community len); 
packet len += community len; 

bcopy (request, packet + packet len, sizeof(request)); 
packet len += sizeof (request); 


fd = socket (AF INET, SOCK DGRAM, 0); 
if (fd < 0) { 

return (-1); 

} 

bzero(&sock, sizeof(sock)); 
sock.sin_family = AF_INET; 
sock.sin_port = 0; 
sock.sin_addr.s_addr = 0; 

rc = bind(fd, &sock, sizeof (sock) ); 
if (re < 0) 

return (-1); 

timeout.tv sec = 3; 

timeout.tv_usec = 0; 

bzero(&dest sock, sizeof (dest_sock) ) ; 
dest sock.sin family = AF INET; 

dest sock.sin port = htons(161); 

dest sock.sin addr.s addr = host addr; 


tries = 0; 

while (++tries < 4) { 

rc = sendto(fd, packet, packet len, 0, &dest_sock, 
sizeof (dest_sock) ) ; 

read mask = 1 << fd; 


rc = select (read mask + 1, &read mask, 0, 0, &timeout); 
if (re <= 0) 

continue; 
sock len = sizeof(dest sock) ; 


packet len = recvfrom(fd, packet, sizeof(packet), 0, 
&dest sock, &sock len); 
if (packet len <= 0) { 
return (-1); 
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) 
rc = extract DPI port (packet, packet len); 
return (rc); 


} 


return (-1); 
} 
static extract_DPI_port (packet, len) 
unsigned char packet[]; 
int len; 
{ 
int offset; 
int port; 


/* should do error checking (like for noSuchName) */ 


offset = len - 2; 
port = (packet[offset] << 8) + packet[offset + 1]; 
return (port); 


SAMPLE DPI FUNCTIONS 


/* DPI parser */ 


#ifdef VM 
#include "manifest.h" 
tendif 


finclude "snmp dpi.h" 


static struct dpi get packet *pDPIget(); 
static struct dpi next packet *pDPInext(); 
static struct dpi set packet *pDPIset(); 
static struct dpi trap packet *pDPItrap(); 
static struct dpi resp packet *pDPIresponse(); 


static void fDPIget(); 
static void ÉDPInext (); 
static void ÉDPIset () ; 
static void fDPItrap(); 
static void fDPIresponse(); 
static int cDPIget (); 
static int cDPInext () ; 
static int cDPIset () ; 
static int cDPItrap(); 
static int cDPIresponse(); 
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static 
static 
static 
struct 


extern 


static 
static 


struct 


SNMP-DPI 


struct snmp dpi hdr *mkDPIhdr(); 
struct dpi get packet *mkDPIget(); 
struct dpi next packet *mkDPInext(); 
dpi set packet *mkDPIset(); 


char *malloc(); 


unsigned char new packet [1024]; 
int packet len; 


snmp dpi hdr *pDPIpacket (packet) 


unsigned char “packet; 


( 


struct snmp dpi hdr *hdr; 


int 


hdr 


LE 


len, offset; 
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= (struct snmp dpi hdr *) malloc(sizeof(struct snmp dpi hdr)); 


(hdr == 0) 
return (0); 


len = (packet [0] << 8) + packet [1]; 
len += 2; 
offset = 2; 


hdr->proto major = packet [offsett++]; 
hdr->proto minor = packet [offset++]; 
hdr->proto release = packet [offset++]1; 
hdr->packet type = packet [offset+t++]; 
switch (hdr->packet type) { 

case SNMP_DPI_GET: 

case SNMP_DPI_REGISTER: 


hdr->packet body.dpi get = 
pDPIget (packet + offset, len - offset); 
break; 


case SNMP DPI GET NEXT: 


hdr->packet body.dpi next = 
pDPInext (packet + offset, len - offset); 
break; 


case SNMP DPI SET: 


hdr->packet body.dpi set = 
pDPIset (packet + offset, len - offset); 
break; 


case SNMP DPI TRAP: 


hdr->packet body.dpi trap = 
pDPItrap(packet + offset, len - offset); 
break; 


case SNMP DPI RESPONSE: 
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hdr->packet body.dpi response = 
pDPIresponse (packet + offset, len - offset); 
break; 
} 
return (hdr); 


} 


static struct dpi_get_packet *pDPIget (packet, len) 
unsigned char *packet; 
int len; 
{ 
struct dpi_get_packet *get; 


int 1; 

get = (struct dpi_get_packet *) 
malloc(sizeof (struct dpi get packet)); 

if (get == 0) 


return (0); 
l = strlen (packet) + 1; 
get->object id = malloc(1); 
strcpy (get->object id, packet); 
return (get); 


} 


static struct dpi_next_packet *pDPInext (packet, len) 
unsigned char *packet; 
int len; 
{ 
struct dpi next packet *next; 
int 1 
unsigned char *cp; 


next = (struct dpi next packet *) 
malloc(sizeof (struct dpi next packet)); 

if (next == 0) 

return (0); 
cp = packet; 
1 = strlen(cp) + 1; 
next->object id = malloc(l); 
strepy(next->object id, cp); 
cp += 1; 
l = strlen(cp) + 1; 
next->group id = malloc(1); 
strepy(next->group id, cp); 
return (next); 


} 


static struct dpi_set_packet *pDPIset (packet, len) 
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unsigned char *packet; 


int 


{ 


} 


len; 


struct dpi_set_packet *set; 
int 1; 
unsigned char *cp; 


if (len == 0) 
return (0); /* nothing to parse */ 
set = (struct dpi_set_packet *) 
malloc(sizeof (struct dpi set packet)); 
if (set == 0) 
return (0); 


cp = packet; 

1 = strlen(cp) + 1; 
set->object id = malloc(l); 
stroepy(set->object id, cp); 
cp += 1; 

set->type = *(cp++); 

1 = (*(cptt) << 8); 

l += *(cp++); 
set->value len = 1; 
set->value = malloc(l); 
bcopy(cp, set->value, 1); 
return (set); 


static struct dpi_trap_packet *pDPItrap (packet, 
unsigned char *packet; 


int 


{ 


} 


len; 
struct dpi_trap_packet *trap; 


trap = (struct dpi_trap_packet *) 
malloc(sizeof (struct dpi_trap_packet) ); 
if (trap == 0) 
return (0); 


trap->generic = *packet; 

trap->specific = *(packet + 1); 

trap->info = pDPIset (packet + 2, len — 2); 
return (trap); 


len) 


static struct dpi resp packet *pDPIresponse (packet, 
unsigned char “packet; 


int 


len; 
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struct dpi resp packet *resp; 


resp = (struct dpi resp packet *) 
malloc(sizeof (struct dpi resp packet)); 
if (resp == 0) 
return (0); 


resp->ret code = *packet; 
resp->ret data = pDPIset(packet + 1, len - 1); 
return (resp); 


} 


void ÉDPIparse (hdr) 
struct snmp_dpi_hdr *hdr; 
{ 

if (hdr == 0) 

return; 

switch (hdr->packet type) ( 

case SNMP DPI GET: 

case SNMP DPI REGISTER: 
fDPIget (hdr); 
break; 
case SNMP DPI GET NEXT: 
fDPInext (hdr) ; 
break; 
case SNMP_DPI_SET: 
ÉDPIset (hdr); 
break; 
case SNMP_DPI_TRAP: 
ÉDPItrap (hdr); 
break; 
case SNMP DPI RESPONSE: 
ÉDPIresponse (hdr); 
break; 


} 
free (hdr); 


} 


static void fDPIget (hdr) 
struct snmp_dpi_hdr *hdr; 
{ 

struct dpi_get_packet *get; 


get = hdr->packet body.dpi get; 
if (get == 0) 

return; 
if (get->object id) 
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} 


free(get->object id); 
free(get); 


static void fDPInext (hdr) 
struct snmp dpi hdr *hdr; 


{ 


} 


struct dpi_next_packet *next; 


next = hdr->packet body.dpi next; 
if (next == 0) 

return; 
if (next->object id) 

free (next->object id); 
if (next->group id) 

free (next->group id); 
free(next); 


static void fDPIset (hdr) 
struct snmp_dpi_hdr *hdr; 


{ 


} 


struct dpi_set_packet *set; 


set = hdr->packet body.dpi set; 
if (set == 0) 
return; 
if (set->object id) 
free(set->object id); 
if (set->value) 
free(set->value); 
free(set); 


static void ÉDPItrap (hdr) 
struct snmp_dpi_hdr *hdr; 


{ 


struct dpi_trap_packet *trap; 
struct dpi_set_packet *set; 


trap = hdr->packet body.dpi trap; 


if (trap == 0) 
return; 

set = trap->info; 

if (set != 0) { 


if (set->object id) 
free(set->object id); 
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if (set->value) 
free(set->value); 
free(set); 
) 
free(trap); 


} 


static void fDPIresponse (hdr) 
struct snmp_dpi_hdr *hdr; 
{ 


struct dpi_resp_packet *resp; 
struct dpi_set_packet *set; 


resp = hdr->packet body.dpi response; 


if (resp == 0) 
return; 

set = resp->ret data; 

if (set != 0) { 


if (set->object id) 
free(set->object id); 
if (set->value) 
free(set->value); 
free(set); 
) 
free(resp); 


} 


unsigned char *cDPIpacket (hdr) 
struct snmp_dpi_hdr *hdr; 
{ 
int rc, len; 
if (hdr == 0) { 
return (0); 
} 
packet_len = 2; 
new packet [packet_len++] = hdr->proto major; 
new packet [packet lent++] hdr->proto minor; 
new packet [packet lent++] hdr->proto release; 
new packet [packet len++] = hdr->packet type; 
switch (hdr->packet type) { 
case SNMP DPI GET: 
case SNMP DPI REGISTER: 
rc = cDPIget (hdr->packet body.dpi get); 
break; 
case SNMP DPI GET NEXT: 
rc = cDPInext (hdr->packet body.dpi next); 
break; 
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} 


case SNMP_DPI_SET: 
rc = cDPIset (hdr->packet body.dpi set); 


break; 


case SNMP_DPI_TRAP: 
rc = cDPItrap(hdr->packet body.dpi trap); 


break; 


case SNMP DPI RESPONSE: 


rc = cDPIresponse(hdr->packet body.dpi response); 


break; 


} 


if (re == -1) 


return 


(0); 


len = packet len - 2; 
new_packet[1] = len & Oxff; 


len >>= 8; 
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new packet [0] = len & Oxff; 
return (new packet); 


static int 
struct dpi get packet *get; 


( 


} 


cDPIget (get) 


if (get->object id == 0) 


return 


(-1); 


strcpy (&new packet [packet len], get->object id); 
packet len += strlen(get->object id) + 1; 


return (0); 


static int 


{ 


} 


cDPInext (next) 
struct dpi next packet *next; 


if (next->object id == 


return 


(-1); 


if (next->group id == 0) 


return 


(-1); 


) 


strcpy (&new packet [packet len], next->object id); 
packet len += strlen(next->object id) + 1; 
strcpy (&new packet [packet len], next->group id); 
packet len += strlen(next->group id) + 1; 


return (0); 


static int 
struct dpi set packet *set; 


{ 


cDPIset (set) 


Carpenter & Wijnen 


May 1991 


[Page 43] 


RFC 1228 SNMP-DPI May 1991 


int len; 


if (set->object id == 0) 


return (-1); 
if ((set->value == 0) && (set->value len != 0)) 
return (-1); 


strcpy (&new packet [packet len], set->object id); 
packet len += strlen(set->object id) + 1; 


new packet [packet len++] = set->type; 

len = set->value len >> 8; 

new packet [packet_len++] = len & Oxff; 

new packet [packet_len++] = set->value len & Oxff; 


bcopy (set->value, &new packet [packet len], set->value len); 
packet len += set->value len; 
return (0); 


} 


static int cDPIresponse (resp) 
struct dpi_resp_packet *resp; 


{ 


int EC; 
if (resp == 0) 
return (-1); 
new packet [packet_len++] = resp->ret code; 
if (resp->ret data != 0) ( 
rc = cDPIset (resp->ret data); 
} else 
re = 0; 


return (rc); 


} 


static int cDPItrap (trap) 
struct dpi_trap_packet *trap; 
{ 


int LC; 
new packet [packet_len++] = trap->generic; 
new packet [packet len++] = trap->specific; 
if (trap->info != 0) 

rc = cDPIset(trap->info); 
else 

rc = 0; 


return (rc); 
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unsi 
int 
char 
int 
char 


{ 


} 


unsi 
char 


{ 
} 


unsi 
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gned char *mkMIBquery (cmd, oid name, group oid, type, len, value) 
cmd; 
*oid name, *group oid; 
type, len; 
*value; 


struct snmp dpi hdr *hdr; 
unsigned char *cp; 


hdr = mkDPIhdr (cmd); 
if (hdr == 0) 
return (0); 
switch (hdr->packet type) ( 
case SNMP DPI GET: 
case SNMP DPI REGISTER: 
hdr->packet body.dpi get = mkDPIget (oid name); 
break; 
case SNMP DPI GET NEXT: 
hdr->packet body.dpi next = mkDPInext (oid name, group oid); 
break; 
case SNMP DPI SET: 
hdr->packet body.dpi set = 
mkDPIset (oid name, type, len, value); 
break; 


) 

cp = cDPIpacket (hdr); 
fDPIparse(hdr); 
return (cp); 


gned char *mkDPIregister(oid name) 
*oid name; 
return (mkMIBquery(SNMP DPI REGISTER, oid name)); 


gned char *mkDPIresponse(ret code, value list) 
ret code; 


struct dpi set packet *value list; 


{ 


struct snmp_dpi_hdr *hdr; 
struct dpi_resp_packet *resp; 
unsigned char *cp; 


hdr = mkDPIhdr(SNMP DPI RESPONSE); 

resp = (struct dpi resp packet *) 
malloc(sizeof (struct dpi resp packet)); 

if (resp == 0) { 
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free(hdr); 
return (0); 
) 
hdr->packet body.dpi response = resp; 
resp->ret code = ret code; 
resp->ret data = value list; 
cp = cDPIpacket (hdr); 
fDPIparse (hdr); 
return (cp); 


} 


unsigned char *mkDPItrap (generic, specific, value_list) 
int generic, specific; 
struct dpi_set_packet *value_list; 
{ 
struct snmp_dpi_hdr *hdr; 
struct dpi trap packet *trap; 
unsigned char *cp; 


hdr = mkDPIhdr(SNMP DPI TRAP); 


trap = (struct dpi trap packet *) 
malloc(sizeof (struct dpi trap packet)); 
if (trap == 0) { 
free (hdr); 


return (0); 
} 
hdr->packet body.dpi trap = trap; 
trap->generic = generic; 
trap->specific = specific; 
trap->info = value list; 
cp = cDPIpacket (hdr); 
fDPIparse (hdr); 
return (cp); 


} 


static struct snmp_dpi_hdr *mkDPIhdr (type) 
int type; 
{ 


struct snmp_dpi_hdr *hdr; 
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hdr = (struct snmp dpi hdr *) malloc(sizeof(struct snmp_dpi_hdr)); 


if (hdr == 0) 

return (0); 
hdr->proto_major SNMP DPI PROTOCOL; 
hdr->proto minor = SNMP DPI VERSION; 
hdr->proto release = SNMP DPI RELEASE; 
hdr->packet type = type; 
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return (hdr); 


} 


static struct dpi_get_packet *mkDPIget (oid_name) 
char *oid_name; 
{ 

struct dpi_get_packet *get; 


int 1; 

get = (struct dpi_get_packet *) 
malloc(sizeof (struct dpi get packet)); 

if (get == 0) 


return (0); 


1 = strlen(oid name) + 1; 
get->object id = malloc(1); 
strepy(get->object id, oid name); 
return (get); 


} 


static struct dpi next packet *mkDPInext (oid name, group oid) 
char *oid name; 
char *group oid; 
{ 
struct dpi next packet *next; 
int ‘Ly 


next = (struct dpi_next_packet *) 
malloc(sizeof (struct dpi_next_packet) ); 

if (next == 0) 

return (0); 
1 = strlen(oid_name) + 1; 
next->object id = malloc(l); 
strcpy (next->object id, oid name); 
1 = strlen(group_oid) + 1; 
next->group id = malloc (l); 
strcpy (next->group id, group oid); 
return (next); 


} 


struct dpi set packet *mkDPIset (oid name, type, len, value) 


char *oid name; 
int type; 

int len; 

char *value; 


{ 


struct dpi_set_packet *set; 
int 1; 
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set = (struct dpi set packet *) 
malloc(sizeof(struct dpi set packet)); 
if (set == 0) 
return (0); 


1 = strlen(oid name) + 1; 
set->object id = malloc(l); 
strepy(set->object id, oid name); 
set->type = type; 

set->value len = len; 

set->value = malloc(len); 

bcopy (value, set->value, len); 
return (set); 


SAMPLE SOURCES FOR ANONYMOUS FTP 


The complete source to two SNMP DPI-related programs is available for 
anonymous ftp from the University of Toronto. The host name to use 
is "vm.utcs.utoronto.ca" (128.100.100.2). The files are in the 
"anonymou.204" minidisk, so one must issue a "cd anonymou.204" after 
having logged in. Don't forget to use the binary transmission mode. 


The Ping Engine 


This program is an SNMP DPI sub-agent which allows network management 
stations to perform remote PINGs. The source to this applications is 
in the file "ping eng.tarbin". The source to the SNMP DPI API is 
also contained within the archive. 


The DPI->SMUX daemon 


This program illustrates what is required to include the SNMP DPI in 
an SNMP agent. This is actually a SMUX-based agent that works with 
the ISODE SNMP agent and provides an interface for SNMP DPI sub- 
agents. The source to this program is in the file "dpid.tarbin". 
ISODE 6.7, or later, is a prerequisite. 
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Security Considerations 


Security issues are not discussed in this memo. 
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